home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / gnu / gnulib / sipp / doc / sipp.2 < prev    next >
Encoding:
GNU Info File  |  1994-02-16  |  48.8 KB  |  1,397 lines
  1. This is Info file sipp, produced by Makeinfo-1.55 from the input file
  2. sipp.tex.
  3.  
  4.    Copyright (C) 1992 Jonas Yngvesson, Inge Wallin
  5.  
  6. 
  7. File: sipp,  Node: Geometric operations,  Next: Object transformations,  Up: Transformations
  8.  
  9. Geometric operations
  10. ====================
  11.  
  12.    To use the vector and matrix functions and macros definied in the
  13. following section, you must include the following line into your
  14. program:
  15.      #include <geometric.h>
  16.    In geometric.h include file, all data types, macros and functions
  17. defined in this section are declared.
  18.  
  19. * Menu:
  20.  
  21. * Vector operations::    Operations on 3-dimensional vectors.
  22. * Matrix operations::    Homogenous transformations defined on matrices
  23.  
  24. 
  25. File: sipp,  Node: Vector operations,  Next: Matrix operations,  Up: Geometric operations
  26.  
  27. Vector operations
  28. -----------------
  29.  
  30.    SIPP uses row vectors and not column vectors. A vector is defined as
  31. follows:
  32.      typedef struct {
  33.          double   x;
  34.          double   y;
  35.          double   z;
  36.      } Vector;
  37.  
  38.    This vector type is used both for directional vectors and points
  39. positional vectors.  In the description below, lower case letters denote
  40. scalar values and upper case letters denote vectors.  All operations are
  41. macros except the last one, `vecnorm()'.
  42.  
  43. `MakeVector(V, xx, yy, zz)'
  44.      Put `xx', `yy' and `zz' in the `x', `y' and `z' slot of the Vector
  45.      `V' respectively.
  46.  
  47. `VecNegate(A)'
  48.      Negate all components of the Vector `A'.
  49.  
  50. `VecDot(A, B)'
  51.      Return the dot product of the two Vectors `A' and `B'.
  52.  
  53. `VecLen(A)'
  54.      Return the length of the Vector `A'.
  55.  
  56. `VecCopy(A, B)'
  57.      Copy the Vector `B' to the Vector `A' (`A = B;' using C notation).
  58.  
  59. `VecAdd(C, A, B)'
  60.      Add the two Vectors `A' and `B' and put the result in `C' (`C = A
  61.      + B;' using C notation).
  62.  
  63. `VecSub(C, A, B)'
  64.      Subtract the Vector `B' from Vector `A' and put the result in `C'
  65.      (`C = A - B;' using C notation).
  66.  
  67. `VecScalMul(B, a, A)'
  68.      Multiply the Vector `A' with the scalar `a' and put the result in
  69.      Vector `B' (`B = a * A;' using C notation).
  70.  
  71. `VecAddS(C, a, A, B)'
  72.      Multiply the Vector `A' with the scalar `a', add it to Vector `B'
  73.      and put the result in Vector `C' (`C = a * A + B;' using C
  74.      notation).
  75.  
  76. `VecComb(C, a, A, b, B)'
  77.      Linearly combine the two Vectors `A' and `B' and put the result in
  78.      Vector `C' (`C' = `a * A + b * B;' using C notation).
  79.  
  80. `VecCross(C, A, B)'
  81.      Cross multiply Vector `A' with Vector `B' and put the result in
  82.      `C' (`C = A' X `B;').
  83.  
  84. `void vecnorm(v)
  85.      '
  86.      `Vector *v;'
  87.  
  88.      Normalize the vector `v', i.e. keep the direction but make it have
  89.      length 1.  The length of `v' should not be equal to 0 to begin
  90.      with.  *NOTE:* This is the only function operating on vectors in
  91.      sipp.  All the other operations are macros.
  92.  
  93. 
  94. File: sipp,  Node: Matrix operations,  Prev: Vector operations,  Up: Geometric operations
  95.  
  96. Matrix operations
  97. -----------------
  98.  
  99.    An full homogenous transformation matrix has 4 x 4 elements.
  100. However, all linear transformations use only 4 x 3 values so to save
  101. space a SIPP transformation matrix only store 4 x 3 values.  Also, if 4
  102. x 4 matrices are used, all vectors must have 4 elements which we want
  103. to avoid.  Thus the transformation matrix used in sipp is defined as
  104. follows:
  105.      typedef struct {
  106.          double mat[4][3];
  107.      } Transf_mat;
  108.  
  109.    We wrap a `struct' around the two-dimensional array since we want to
  110. be able to say things like `&mat' without being forced to write
  111. `(Transf_mat *) &mat[0]' which we find horrendously ugly.
  112.  
  113.    SIPP has a predefined identity matrix declared in geometric.h which
  114. you can use:
  115.      extern Transf_mat   ident_matrix;
  116.    The rest of this section describes the macro and functions defined in
  117. the SIPP library which operate on SIPP transformation matrices.
  118.  
  119. `MatCopy(A, B)'
  120.      This macro copies the matrix `B' to the matrix `A'. `A' and `B'
  121.      must both be pointers. *NOTE:* This is the only macro operating on
  122.      matrices in SIPP.  All other operations listed here are functions.
  123.  
  124. `Transf_mat *transf_mat_create(initmat)'
  125.      `Transf_mat *initmat;'
  126.  
  127.      Allocate memory for a new transformation matrix and if `initmat' is
  128.      equal to `NULL', set the new matrix to the identity matrix.
  129.      Otherwise set the new matrix to the contents of `initmat'.  Return
  130.      a pointer to the new matrix.
  131.  
  132. `Transf_mat *transf_mat_destruct(mat)'
  133.      `Transf_mat *initmat;'
  134.  
  135.      Free the memory associated with the matrix `mat'.
  136.  
  137. `void mat_translate(mat, dx, dy, dz)'
  138.      `Transf_mat *mat;
  139.      double dx;
  140.      double dy;
  141.      double dz;'
  142.  
  143.      Set `mat' to the transformation matrix that represents the
  144.      concatenation of the previous transformation in `mat' and a
  145.      translation along the vector (`dx', `dy', `dz').
  146.  
  147. `void mat_rotate_x(mat, ang)'
  148.      `Transf_mat *mat;
  149.      double ang;'
  150.  
  151.      Set `mat' to the transformation matrix that represents the
  152.      concatenation of the previous transformation in `mat' and a
  153.      rotation with the angle `ang' around the X axis. The angle `ang'
  154.      is expressed in radians.
  155.  
  156. `void mat_rotate_y(mat, ang)'
  157.      `Transf_mat *mat;
  158.      double ang;'
  159.  
  160.      Set `mat' to the transformation matrix that represents the
  161.      concatenation of the previous transformation in `mat' and a
  162.      rotation with the angle `ang' around the Y axis.  The angle `ang'
  163.      is expressed in radians.
  164.  
  165. `void mat_rotate_z(mat, ang)'
  166.      `Transf_mat *mat;
  167.      double ang;'
  168.  
  169.      Set `mat' to the transformation matrix that represents the
  170.      concatenation of the previous transformation in `mat' and a
  171.      rotation with the angle `ang' around the Z axis.  The angle `ang'
  172.      is expressed in radians.
  173.  
  174. `void mat_rotate(mat, point, vector, ang)'
  175.      `Transf_mat *mat;
  176.      Vector *point;
  177.      Vector *vector;
  178.      double ang;'
  179.  
  180.      Set `mat' to the transformation matrix that represents the
  181.      concatenation of the previous transformation in `mat' and a
  182.      rotation with the angle `ang' around the line represented by the
  183.      point `point' and the vector `vector'.  The angle `ang' is
  184.      expressed in radians.
  185.  
  186. `void mat_scale(mat, xscale, yscale, zscale)'
  187.      `Transf_mat *mat;
  188.      double xscale;
  189.      double yscale;
  190.      double zscale;'
  191.  
  192.      Set `mat' to the transformation matrix that represents the
  193.      concatenation of the previous transformation in `mat' and a scaling
  194.      with the scaling factors (`xscale', `yscale', `zscale').
  195.  
  196. `void mat_mirror_plane(mat, point, normal)'
  197.      `Transf_mat *mat;
  198.      Vector *point;
  199.      Vector *normal;'
  200.  
  201.      Set `mat' to the transformation matrix that represents the
  202.      concatenation of the previous transformation in `mat' and a
  203.      mirroring in the plane defined by the point `point' and the normal
  204.      vector `normal'.
  205.  
  206. `void mat_mul(res, a, b)'
  207.      `Transf_mat *res;
  208.      Transf_mat *a;
  209.      Transf_mat *b;'
  210.  
  211.      Multiply the two matrices `a' and `b' and put the result in the
  212.      matrix `res'.  All three parameters are pointers to matrices.  It
  213.      is possible for `res' to point at the same matrix as either `a' or
  214.      `b' since the result is stored in a temporary matrix during the
  215.      computations.
  216.  
  217. `void point_transform(res, vec, mat)'
  218.      `Vector *res;
  219.      Vector *vec;
  220.      Transf_mat *mat;'
  221.  
  222.      Transform the point (vector) `vec' with the transformation matrix
  223.      `mat' and put the result into the vector `res'.  The two vectors
  224.      `res' and `vec' should not be the same vector since no temporary
  225.      is used during the computations.
  226.  
  227. 
  228. File: sipp,  Node: Object transformations,  Prev: Geometric operations,  Up: Transformations
  229.  
  230. Object transformations
  231. ======================
  232.  
  233.    There are two functions for reading and writing such matrices from
  234. and to objects:
  235.  
  236.      Transf_mat *
  237.      object_get_transf(object, matrix)
  238.              Object      *object;
  239.              Transf_mat  *matrix;
  240.    This function retrieves the transformation matrix of the object
  241. pointed to by `object'. If `matrix' is `NULL' the function will
  242. allocate space for a matrix, copy the object's matrix into this space
  243. and return a pointer to the new matrix. If `matrix' is not `NULL' the
  244. objects transformation matrix is copied into the space its pointing to
  245. and the same pointer is returned.
  246.  
  247.      void
  248.      object_set_transf(object, matrix)
  249.              Object      *object;
  250.              Transf_mat  *matrix;
  251.    This function copies the matrix pointed to by `matrix' into
  252. `object''s transformation matrix.
  253.  
  254.    There is also a special function for resetting an object's
  255. transformation matrix to the identity matrix, i.e. no transformation at
  256. all:
  257.      void
  258.      object_clear_transf(object)
  259.              Object  *object;
  260.  
  261. Applying transformations
  262. ------------------------
  263.  
  264.    The transformations in this section are all applied to an object
  265. without altering its previous transformations, i.e. they will be
  266. applied after the previous transformations have been completed. What
  267. actually happens is that the matrix that specifies the new
  268. transformation is post multiplied into the objects current matrix.
  269.  
  270.    There are four functions for rotating objects:
  271.      void
  272.      object_rot_x(object, angle)
  273.              Object  *object;
  274.              double   angle;
  275.      
  276.      void
  277.      object_rot_y(object, angle)
  278.              Object  *object;
  279.              double   angle;
  280.      
  281.      void
  282.      object_rot_z(object, angle)
  283.              Object  *object;
  284.              double   angle;
  285.      
  286.      void
  287.      object_rot(object, point, vector, angle)
  288.              Object  *object;
  289.              Vector  *point;
  290.              Vector  *vector;
  291.              double   angle;
  292.    The first three functions rotate an object about one of the primary
  293. axes in the parent object's local coordinate system. `angle' is the
  294. rotation angle given in radians. Positive rotation is given by the
  295. "right hand rule", i.e. counterclockwise when looking along the axis
  296. towards the origin.
  297.  
  298.    The fourth function is a more general rotation. It specifies a
  299. rotation of an object about an arbitrary axis. The axis is defined as
  300. passing through `point' in the direction of `vector', both are
  301. described in the parent object's local coordinate system. `angle' is
  302. the rotation angle in radians and positive rotation is defined in the
  303. same way as for the previous three functions.
  304.  
  305.    For scaling an object the following function is used:
  306.      void
  307.      object_scale(object, sx, sy, sz)
  308.              Object  *object;
  309.              double   sx, sy, sz;
  310.    The object pointed to by `object' is scaled towards the origin along
  311. the three principal axes with the three scaling factors `sx, sy' and
  312. `sz' respectively.
  313.  
  314.    The last standard transformation is translation:
  315.      void
  316.      object_move(object, dx, dy, dz)
  317.              Object  *object;
  318.              double   dx, dy, dz;
  319.    The object is translated along the vector (`dx dy dz') from its
  320. current position. Note that the movement is relative and not absolute.
  321. The translation vector is given in the parent coordinate system.
  322.  
  323.    There is also a general transformation function that post-multiplies
  324. any transformation matrix into the current matrix of an object:
  325.      void
  326.      object_transform(object, matrix)
  327.              Object      *object;
  328.              Transf_mat  *matrix;
  329.  
  330. 
  331. File: sipp,  Node: Lights,  Next: Shadows,  Prev: Transformations,  Up: Top
  332.  
  333. Lights
  334. ******
  335.  
  336.    SIPP supports two basic kinds of lights, simple lightsources and
  337. spotlights. The main difference is that spotlights can cast shadows,
  338. while simple lightsources can not. The functions that create any of
  339. these lights return a pointer to a `Lightsource' structure. This
  340. pointer is used for later manipulations of the light such as moving it
  341. or turning it off or on. If there is no need for later manipulations
  342. these pointers can safely be discarded. SIPP keeps track of all created
  343. lightsources internally.
  344.  
  345. * Menu:
  346.  
  347. * Creating lights::     Creating lightsources and spotlights.
  348. * Manipulating lights:: Changing already existing lights.
  349.  
  350. 
  351. File: sipp,  Node: Creating lights,  Next: Manipulating lights,  Up: Lights
  352.  
  353. Creating lights
  354. ===============
  355.  
  356.    Simple lightsources can be of two types, directional and point
  357. lightsources. Directional lightsources emit light that is parallel in
  358. every point in the scene, similar to light from the sun. Point
  359. lightsources emit light from a single point in space.
  360.      Lightsource *
  361.      lightsource_create(x, y, z, red, green, blue, type)
  362.              double x, y, z;
  363.              double red, green, blue;
  364.              int    type;
  365.  
  366.    * `x, y, z'
  367.  
  368.      If a directional lightsource is created these numbers specifies a
  369.      vector pointing to the lightsource. If it is a point lightsource
  370.      the numbers specify the exact location of it.
  371.  
  372.    * `red, green, blue'
  373.  
  374.      These numbers indicate the color of the emitted light. All three
  375.      should be in the range [0, 1].
  376.  
  377.    * `type'
  378.  
  379.      This parameter defines which type of lightsource that is created.
  380.      It should be one of the predefined values `LIGHT_DIRECTION' or
  381.      `LIGHT_POINT'.
  382.  
  383.    A spotlight emits a "cone" of light. There are two types of
  384. spotlights in SIPP. One has a sharp edge on its lightcone and the other
  385. has a soft edge that blends out smoothly. Rendering scenes with soft
  386. edged spotlights takes slightly longer time than scenes with only sharp
  387. edged spotlights.
  388.      Lightsource *
  389.      spotlight_create(x1, y1, z1, x2, y2, z2, opening, red, green, blue,
  390.                       type, shadow)
  391.              double x1, y1, z1;
  392.              double x2, y2, z2;
  393.              double opening;
  394.              double red, green, blue;
  395.              int    type;
  396.              bool   shadow;
  397.  
  398.    * `x1, y1, z1'
  399.  
  400.      This is the position of the spotlight.
  401.  
  402.    * `x2, y2, z2'
  403.  
  404.      This is a point at which the spotlight is pointing. It is in the
  405.      middle of the lightcone.
  406.  
  407.    * `opening'
  408.  
  409.      This defines, in degrees, the opening angle of the lightcone. The
  410.      cone defined will be completely lit, a soft edged lightcone will
  411.      start to blend out outside this angle.
  412.  
  413.    * `red, green, blue'
  414.  
  415.      The color of the emitted light. All three numbers are in the range
  416.      [0, 1].
  417.  
  418.    * `type'
  419.  
  420.      Tells SIPP which type of spotlight to create. Should be one of the
  421.      predefined values `SPOT_SHARP' or `SPOT_SOFT'.
  422.  
  423.    * `shadow'
  424.  
  425.      If `TRUE', the light from the spotlight will be able to cast
  426.      shadows, otherwise not. Whether shadows actually are cast or not
  427.      depend on which value `sipp_shadows()' (*Note Initializations::)
  428.      was called with last.
  429.  
  430.    There is also a function for releasing the memory used by a
  431. lightsource or a spotlight.
  432.      void
  433.      light_destruct(light)
  434.              Lightsource  *light;
  435.  
  436.    * `light'
  437.  
  438.      Pointer to the lightsource or spotlight that is to be destructed.
  439.  
  440. 
  441. File: sipp,  Node: Manipulating lights,  Prev: Creating lights,  Up: Lights
  442.  
  443. Manipulating lights
  444. ===================
  445.  
  446.    When lights have been created they can be manipulated in various
  447. ways.  There are functions that are specific for lightsources, functions
  448. specific for spotlights and generic functions which works for both kind
  449. of lights.
  450.  
  451.      void
  452.      lightsource_put(lightsrc, x, y, z)
  453.              Lightsource  *lightsrc;
  454.              double        x, y, z;
  455.    This function is used to modify the direction, or position, of a
  456. lightsource. If (`x, y, z') are interpreted as a position or as a
  457. direction vector depends on whether `lightsrc' is pointing at a point
  458. lightsource or a directional lightsource.
  459.  
  460.      void
  461.      spotlight_pos(spot, x, y, z)
  462.              Lightsource  *spot;
  463.              double        x, y, z;
  464. Modify the position of a spotlight.
  465.  
  466.      void
  467.      spotlight_at(spot, x, y, z)
  468.              Lightsource  *spot;
  469.              double        x, y, z;
  470.    Modify the position the spotlight is pointing at.
  471.  
  472.      void
  473.      spotlight_opening(spot, opening)
  474.              Lightsource  *spot;
  475.              double        opening;
  476.    Modify the opening angle of the lightcone of a spotlight. `opening'
  477. is given in degrees.
  478.  
  479.      void
  480.      spotlight_shadows(spot, flag)
  481.              Lightsource  *spot;
  482.              bool          flag;
  483.    Turn shadow casting on or off for a specific spotlight. `flag' set
  484. to `TRUE' means that the spotlight can cast shadows.
  485.  
  486.      void
  487.      light_color(light, red, green, blue)
  488.              Lightsource  *light;
  489.              double        red, green, blue;
  490.    Change the color of the emitted light from a lightsource or a
  491. spotlight.  (`red, green, blue') are all numbers in the range [0, 1].
  492.  
  493.      void
  494.      light_active(light, flag)
  495.              Lightsource  *light;
  496.              bool          flag;
  497.    Turn a lightsource or a spotlight on or off. If `flag' is `TRUE' the
  498. light is activated.
  499.  
  500.    The last function is not really a manipulation function. It evaluates
  501. how much light from a certain lightsource or spotlight that reaches a
  502. specific point in the scene. It also calculates a vector pointing from
  503. this point at the light. The return value is a number in the range [0,
  504. 1] where 1 means that all light from the lightsource reaches the point
  505. and 0 means that none of the light reaches it. The function is intended
  506. to be used in shading functions.  We describe it formally here and
  507. refer to the chapter on how to write your own shaders for instructions
  508. and examples of how to use it (*Note Writing your own shaders::).
  509.      double
  510.      light_eval(light, position, light_vector)
  511.              Lightsource  *light;
  512.              Vector       *position;
  513.              Vector       *light_vector;
  514.  
  515.    * `light'
  516.  
  517.      Pointer to the lightsource or spotlight to evaluate.
  518.  
  519.    * `position'
  520.  
  521.      Pointer to a vector specifying which point in the scene we want to
  522.      check the illumination for. The position is given in the world
  523.      coordinate system.
  524.  
  525.    * `light_vector'
  526.  
  527.      Points to a space where `light_eval()' will store a normalized
  528.      vector pointing from `position' at the light.
  529.  
  530. 
  531. File: sipp,  Node: Shadows,  Next: Viewpoint and cameras,  Prev: Lights,  Up: Top
  532.  
  533. Shadows
  534. *******
  535.  
  536.    SIPP creates shadows with a technique called depth maps.  A detailed
  537. description of this technique can be found in the article Rendering
  538. Antialiased Shadows with Depth Maps by Reeves, Salesin and Cook in the
  539. Proceedings of SIGGRAPH 1987.
  540.  
  541.    In principle, a depth map is generated for each light that should
  542. cast shadows. The depth map is simply an image of the scene, as seen
  543. from the light, but instead of a color we store the depth (Z-buffer
  544. value) in each "pixel". The finished map will contain the distance to
  545. the object closest to the light in each point.
  546.  
  547.    When the scene is rendered we transform each point we are shading
  548. into depth map coordinates and if it is further away from the light
  549. than the value stored in the corresponding point in the depth map, the
  550. point is in shadow. The actual implementation is of course a bit more
  551. complicated with some sampling and filtering but we won't go into that.
  552.  
  553.    The reason we describe this algorithm at all is that it is easier to
  554. understand how to get good looking shadows and why shadows sometimes
  555. look weird if one have an understanding of the underlying process.
  556.  
  557.    First of all: The shadows are generated by sampling in the depth
  558. maps.  Sampling usually means we are in danger of aliasing and this is
  559. very true in our case. SIPP automatically fits the depth map for a
  560. spotlight so that it covers all area lit by the spotlight's light cone
  561. (*Note Creating lights::). If this area is large and the depth map
  562. resolution is low, the shadows will get very jagged.
  563.  
  564.    Also, if we have a large surface that is close to perpendicular to
  565. the depth map plane, the depth map "pixels" will be projected as long
  566. stripes on that surface, so even if the depth map resolution is high, a
  567. shadow cast on such a surface will suffer from aliasing (be jagged).
  568.  
  569.    So, if the edges of a shadow look weird, try increasing the size of
  570. the depth map (the depth map size is set with `sipp_shadows()', *Note
  571. Initializations::). If they still look weird, or you run out of memory,
  572. try changing the position of the lightsource that generate the shadow.
  573. After some tweaking it is usually possible to get fairly decent shadows.
  574.  
  575. 
  576. File: sipp,  Node: Viewpoint and cameras,  Next: Rendering,  Prev: Shadows,  Up: Top
  577.  
  578. Viewpoint and cameras
  579. *********************
  580.  
  581.    The viewpoint model used in SIPP are a fairly standard one. A point
  582. where the camera is located, a point which the camera looks at, a vector
  583. telling which direction is up and the focal distance in the camera.  The
  584. user can create several virtual cameras and tell SIPP to use any of
  585. them as viewpoint when rendering an image. There is also a predefined
  586. camera called `sipp_camera' which is the default viewpoint. When
  587. `sipp_init()' is called, this camera is initialized to be located in (0
  588. 0 10), looking at the origin, with the world y-axis as the up direction
  589. and a focal factor (see below) of 0.25. The user can of course change
  590. these values to whatever he likes.
  591.  
  592.    To create and manipulate cameras, SIPP provide the following
  593. functions:
  594.  
  595.      Camera *
  596.      camera_create()
  597.    This function creates a new virtual camera and initializes it to the
  598. same default setting as `sipp_init()' does with `sipp_camera' (see
  599. above).
  600.  
  601.      void
  602.      camera_destruct(camera)
  603.              Camera  *camera;
  604.    Release the memory used by a virtual camera. `sipp_camera' can't be
  605. destructed and if the camera which is currently used as viewpoint is
  606. destructed, the current viewpoint will be reset to `sipp_camera'.
  607.  
  608.      void
  609.      camera_position(camera, x, y, z)
  610.              Camera  *camera;
  611.              double   x, y, z;
  612.    Place `camera' at the position (`x, y, z') in the world coordinate
  613. system.
  614.  
  615.      void
  616.      camera_look_at(camera, x, y, z)
  617.              Camera  *camera;
  618.              double   x, y, z;
  619.    Set `camera' to look at the point (`x, y, z') in the world
  620. coordinate system.
  621.  
  622.      void
  623.      camera_up(camera, x, y, z)
  624.              Camera  *camera;
  625.              double   x, y, z;
  626.    Set the up direction of `camera' to be the vector (`x, y, z') in the
  627. world coordinate system. The up direction is not allowed to be parallel
  628. to the viewing direction, i.e. the vector from the camera position to
  629. the point it is looking at.
  630.  
  631.      void
  632.      camera_focal(camera, focal)
  633.              Camera  *camera;
  634.              double   focal;
  635.    Set `camera''s focal factor to be `focal'. The focal factor is the
  636. ratio between half the screen height and the distance from the
  637. viewpoint to the screen. Another way of describing it is tan(v/2) where
  638. v is the opening angle of the view. A large focal factor will result in
  639. a wide angle view while a small factor will give a telescopic effect.
  640. See figure below:
  641.                                      screen
  642.                                      |
  643.                                      | s
  644.          viewpoint                   |
  645.              *-----------------------|
  646.                          d           |
  647.                                      |
  648.                                      |
  649.      
  650.      
  651.              focal = s / d
  652.  
  653.      void
  654.      camera_params(camera, x1, y1, z1, x2, y2, z2, ux, uy, uz, focal)
  655.              Camera  *camera;
  656.              double   x1, y1, z1;
  657.              double   x2, y2, z2;
  658.              double   ux, uy, uz;
  659.              double   focal;
  660.    Set all parameters of a camera in one call. (`x1, y1, z1') is the
  661. position, (`x2, y2, z2') is the point the camera is looking at, (`ux,
  662. uy, uz') is the up direction and `focal' is the focal factor. Note that
  663. the up direction is not allowed to be parallel to the viewing
  664. direction, i.e. the vector from the camera position to the point it is
  665. looking at.
  666.  
  667.      void
  668.      camera_use(camera)
  669.              Camera  *camera;
  670.    Tell SIPP to use `camera' as the current viewpoint.
  671.  
  672. 
  673. File: sipp,  Node: Rendering,  Next: Shaders,  Prev: Viewpoint and cameras,  Up: Top
  674.  
  675. Rendering
  676. *********
  677.  
  678.    SIPP can render images in four different modes:
  679.    * `PHONG' rendering interpolates surface normal and texture
  680.      coordinates across polygons and calls the appropriate shading
  681.      function in each point. This mode is the slowest but produces the
  682.      best results and is the only mode where any texturing effects can
  683.      be used. Note that most of the interesting effects that is
  684.      possible to produce with SIPP, e.g. shadows and position dependent
  685.      light (spotlights, point lights), are in fact texturing effects.
  686.  
  687.    * `GOURAUD' rendering only calls the shader in the vertices of the
  688.      polygons and then interpolates the calculated colors across them.
  689.      The opacities returned from the shader is interpolated in the same
  690.      manner.
  691.  
  692.    * `FLAT' rendering calls the shader once per polygon and then fills
  693.      the whole polygon with the resulting color. The whole polygon will
  694.      also get the opacity returned from the shader.
  695.  
  696.    * `LINE' rendering will produce a monochrome line image with only the
  697.      edges of the polygons drawn. No shaders are involved. No hidden
  698.      line elimination are performed but backfacing polygons are not
  699.      drawn unless specifically ordered with `sipp_show_backfaces()'
  700.      (*Note Initializations::).   There are two ways of rendering the
  701. currently specified scene.  They differ in the place to which the
  702. rendered image is sent.
  703.  
  704. * Menu:
  705.  
  706. * Rendering to file::          Rendering into a PPM or PBM file.
  707. * Rendering to other devices:: Rendering with a user specified function
  708. * Rendering to in-core images:: Rendering to an image in memory
  709.  
  710. 
  711. File: sipp,  Node: Rendering to file,  Next: Rendering to other devices,  Up: Rendering
  712.  
  713. Rendering to file
  714. =================
  715.  
  716.    There are two functions for rendering into a file.
  717.  
  718.      void
  719.      render_image_file(width, height, file, mode, oversampling)
  720.              int    width, height;
  721.              FILE  *file;
  722.              int    mode;
  723.              int    oversampling;
  724.  
  725.    * `width, height'
  726.  
  727.      These parameters specify the size of the image in pixels. If the
  728.      two sizes are different, the focal factor of the camera (*Note
  729.      Viewpoint and cameras::) is defined to refer to the smaller of the
  730.      two.
  731.  
  732.    * `file'
  733.  
  734.      This is a pointer to an open file on which the image will be
  735.      written. If the system supports it, it could just as well be a
  736.      pipe or a socket of course.
  737.  
  738.    * `mode'
  739.  
  740.      This defines the rendering mode, `LINE', `FLAT', `GOURAUD' or
  741.      `PHONG' as described earlier.
  742.  
  743.    * `oversampling'
  744.  
  745.      This parameter defines how much oversampling should be performed
  746.      for anti-aliasing. Each pixel will be rendered internally as a
  747.      mesh of (`oversampling x oversampling') subpixels and the average
  748.      color in this mesh will be used to represent the final pixel. This
  749.      parameter is ignored in `LINE' mode.
  750.  
  751.    The other function for rendering into a file is useful when doing
  752. animations. Since video formats are usually interlaced, it is possible
  753. to get a smoother motion if each field (half-frame) is rendered
  754. separately and the motion is updated between these fields instead of
  755. between frames. Unfortunately `LINE' rendering can not be used when
  756. rendering fields.
  757.  
  758.      void
  759.      render_field_file(width, height, file, mode, oversampling, field)
  760.              int    width, height;
  761.              FILE  *file;
  762.              int    mode;
  763.              int    oversampling;
  764.              int    field;
  765.  
  766.    * `width, height'
  767.  
  768.      These parameters specify the size of the image in pixels. It is the
  769.      height of the frame that should be specified in `height', not the
  770.      field, the field height is determined internally.
  771.  
  772.    * `file'
  773.  
  774.      This is a pointer to an open file on which the field will be
  775.      written. If the system supports it, it could just as well be a
  776.      pipe or a socket of course.
  777.  
  778.    * `mode'
  779.  
  780.      This defines the rendering mode, `FLAT', `GOURAUD' or `PHONG' as
  781.      described earlier.
  782.  
  783.    * `oversampling'
  784.  
  785.      This parameter defines how much oversampling should be performed
  786.      for anti-aliasing.
  787.  
  788.    * `field'
  789.  
  790.      This defines if an odd or even field should be produced. The value
  791.      should be one of the predefined constants `ODD' or `EVEN'.  `ODD'
  792.      will result in only odd scanlines being rendered, with 0 being the
  793.      top scanline.
  794.  
  795. 
  796. File: sipp,  Node: Rendering to other devices,  Next: Rendering to in-core images,  Prev: Rendering to file,  Up: Rendering
  797.  
  798. Rendering to other devices
  799. ==========================
  800.  
  801.    Sometimes one does not want the rendered image to be stored in a
  802. file.  Perhaps it should be displayed in a window or further processed
  803. in some way. SIPP provides a way to have a function called for each
  804. rendered pixel, or for each line if a line image is rendered. The
  805. function is given information about which pixel it is and what
  806. resulting color it got.  Since one of the most used applications of
  807. this probably is rendering to a pixmap in memory, SIPP has special
  808. support for that.  *Note Rendering to in-core images::.
  809.  
  810.    Use a call to the following function to render to another device
  811. than a file:
  812.  
  813.      void
  814.      render_image_func(width, height, pix_func, data, mode, oversampling)
  815.              int    width, height;
  816.              void (*pix_func)();
  817.              void  *data;
  818.              int    mode;
  819.              int    oversampling;
  820.  
  821.    * `width, height'
  822.  
  823.      These parameters specify the size of the image in pixels. If the
  824.      two sizes are different, the focal factor of the camera (*Note
  825.      Viewpoint and cameras::) is defined to refer to the smaller of the
  826.      two.
  827.  
  828.    * `pix_func'
  829.  
  830.      This is a pointer to a function that SIPP calls once for each
  831.      rendered pixel.  If `LINE' rendering is used it is called for each
  832.      line instead. The function must have the following interface:
  833.  
  834.           void
  835.           my_pixel_function(data, col, row, red, green, blue)
  836.                   my_data       *data;
  837.                   int            col, row;
  838.                   unsigned char  red, green, blue;
  839.  
  840.         * `data' This is the same `data' pointer that was passed to
  841.           `render_image_func()'.
  842.  
  843.         * `col, row' Specifies position of the pixel. (0, 0) is upper
  844.           left.
  845.  
  846.         * `red, green, blue' This is the color of the pixel quantified
  847.           to 24 bits, 8 bits for each of red, green and blue.
  848.  
  849.      If `LINE' rendering is used instead, the user provided function is
  850.      called for each rendered line instead of each pixel and should
  851.      have the following interface:
  852.           void
  853.           my_line_function(data, col1, row1, col2, row2)
  854.                   my_data       *data;
  855.                   int            col1, row1;
  856.                   int            col2, row2;
  857.  
  858.         * `data' This is the same `data' pointer that was passed to
  859.           `render_image_func()'.
  860.  
  861.         * `row1, col1, row2, col2' Specification of the two endpoints
  862.           of the line. (0, 0) is upper left,
  863.  
  864.    * `data'
  865.  
  866.      This is a pointer to any data structure that the pixel function
  867.      (see next item) needs. It could be a pointer to a specific pixmap
  868.      or window or whatever.
  869.  
  870.    * `mode'
  871.  
  872.      This defines the rendering mode, `LINE', `FLAT', `GOURAUD' or
  873.      `PHONG' as described earlier.
  874.  
  875.    * `oversampling'
  876.  
  877.      This parameter defines how much oversampling should be performed
  878.      for anti-aliasing. Each pixel will be rendered internally as a
  879.      mesh of (`oversampling x oversampling') subpixels and the average
  880.      color in this mesh will be used to represent the final pixel. This
  881.      parameter is ignored in `LINE' mode.
  882.  
  883.    There is also a corresponding function to `render_field_file()' for
  884. rendering a field into a user defined place. As in that function,
  885. `LINE' rendering can not be used when rendering fields.
  886.  
  887.      void
  888.      render_field_func(width, height, pix_func, data, mode, oversampling, field)
  889.              int    width, height;
  890.              void (*pix_func)();
  891.              void  *data;
  892.              int    mode;
  893.              int    oversampling;
  894.              int    field;
  895.    All parameters have the same meaning as in `render_image_func()'
  896. except the last one.
  897.  
  898.    * `field'
  899.  
  900.      This defines if an odd or even field should be produced. The value
  901.      should be one of the predefined constants `ODD' or `EVEN'.  `ODD'
  902.      will result in only odd scanlines being rendered, with 0 being the
  903.      top scanline.
  904.  
  905. 
  906. File: sipp,  Node: Rendering to in-core images,  Prev: Rendering to other devices,  Up: Rendering
  907.  
  908. Rendering to in-core images
  909. ===========================
  910.  
  911.    To people who want to create images in memory, we provide two image
  912. formats similar in kind to the Portable Pixmap (ppm) and Portable Bitmap
  913. (pbm).  Only very simple operations are defined on them, but the
  914. definition of the types are also given here, so those who want to write
  915. their own functions operating on the images can do so.
  916.  
  917. * Menu:
  918.  
  919. * Sipp_pixmap:: The pixmap type (24 bits/pixel)
  920. * Sipp_bitmap:: The pixmap type (1 bit/pixel)
  921.  
  922. 
  923. File: sipp,  Node: Sipp_pixmap,  Next: Sipp_bitmap,  Up: Rendering to in-core images
  924.  
  925. The Sipp_pixmap image data type
  926. -------------------------------
  927.  
  928.    To use the pixmap operations you must put the following line into
  929. your source file:
  930.      #include <sipp_pixmap.h>
  931.    In this include file, the `Sipp_pixmap' data type is defined as well
  932. as all operations operating on it.  Only the most basic operations are
  933. defined.
  934.  
  935.    A `Sipp_pixmap' is defined like this:
  936.      typedef struct {
  937.          int      width;             /* Width of the pixmap */
  938.          int      height;            /* Height of the pixmap */
  939.          unsigned char * buffer;     /* A pointer to the image. */
  940.      } Sipp_pixmap;
  941.    The pointer `buffer' is a pointer to the image where each pixel is
  942. stored as three unsigned chars in the order red, green, blue.  Thus, the
  943. buffer is 3 * `width' * `height' bytes long.
  944.  
  945.    The following functions are defined for a `Sipp_pixmap':
  946.  
  947.      Sipp_pixmap *
  948.      sipp_pixmap_create(width, height)
  949.              int  width;
  950.              int  height;
  951.    Returns a newly created `Sipp_pixmap' with the given size.  The new
  952. pixmap is filled with zeros on creation.
  953.  
  954.      void
  955.      sipp_pixmap_destruct(pm)
  956.              Sipp_pixmap *pm;
  957.    Frees all memory associated to the `Sipp_pixmap pm' and returns it
  958. to the heap.
  959.  
  960.      void
  961.      sipp_pixmap_set_pixel(pm, col, row, red, grn, blu)
  962.              Sipp_pixmap   *pm;
  963.              int            col;
  964.              int            row;
  965.              unsigned char  red;
  966.              unsigned char  grn;
  967.              unsigned char  blu;
  968.    Set the pixel at (`col', `row') in pixmap `pm' to be the color
  969. (`red', `grn', `blu'). (0, 0) is upper left.  Note that this function
  970. is directly usable in `render_image_func()' defined in *Note Rendering
  971. to other devices::, when using the `FLAT', `GOURAUD' or `PHONG' mode of
  972. rendering.
  973.  
  974.      void
  975.      sipp_pixmap_write(file, pm)
  976.              FILE         *file;
  977.              Sipp_pixmap  *pm;
  978.    Write the pixmap `pm' to the open file `file'.  The image is written
  979. in the Portable Pixmap format P6 (raw ppm), the same format SIPP is
  980. using when rendering to a file.
  981.  
  982. 
  983. File: sipp,  Node: Sipp_bitmap,  Prev: Sipp_pixmap,  Up: Rendering to in-core images
  984.  
  985. The Sipp_bitmap image data type
  986. -------------------------------
  987.  
  988.    To use the pixmap operations you must put the following line into
  989. your source file:
  990.      #include <sipp_bitmap.h>
  991.  
  992.    In this include file, the `Sipp_bitmap' data type is defined as well
  993. as all operations operating on it.  Only the most basic operations are
  994. defined.
  995.  
  996.    A `Sipp_bitmap' is defined like this:
  997.      typedef struct {
  998.          int   width;                 /* Width of the bitmap in pixels */
  999.          int   height;                /* Height of the bitmap in pixels */
  1000.          int   width_bytes;           /* Width of the bitmap in bytes. */
  1001.          unsigned char * buffer;             /* A pointer to the image. */
  1002.      } Sipp_bitmap;
  1003.    The pointer `buffer' is a pointer to the image where each pixel is a
  1004. bit in an unsigned char, eight pixels per char.  If the `width' field
  1005. is not a multiple of 8, the last bits in the last byte of a row are not
  1006. used.  The most significant bit in each byte is the leftmost pixel. The
  1007. entire buffer is `width_bytes' * `height' bytes long.
  1008.  
  1009.    The following functions operate on a `Sipp_bitmap':
  1010.  
  1011.      Sipp_bitmap *
  1012.      sipp_bitmap_create(width, height)
  1013.              int width;
  1014.              int height;
  1015.    Returns a new `Sipp_bitmap' with the given size.  The new bitmap is
  1016. filled with zeros on creation.
  1017.  
  1018.      void
  1019.      sipp_bitmap_destruct(bm)
  1020.              Sipp_bitmap  *bm;
  1021.    Frees all memory associated to the `Sipp_bitmap bm' and returns it
  1022. to the heap.
  1023.  
  1024.      void
  1025.      sipp_bitmap_line(bm, col1, row1, col2, row2)
  1026.              Sipp_bitmap  *bm;
  1027.              int           col1;
  1028.              int           row1;
  1029.              int           col2;
  1030.              int           row2;
  1031.    Draw a line from (`col1', `row1') to (`col2', `row2') in the bitmap
  1032. `bm'. (0, 0) is upper left. Note that this function is directly usable
  1033. in `render_image_func()' defined in *Note Rendering to other devices::,
  1034. when using the `LINE' mode of rendering.
  1035.  
  1036.      void
  1037.      sipp_bitmap_write(file, bm)
  1038.              FILE         *file;
  1039.              Sipp_bitmap  *bm;
  1040.    Write the bitmap `bm' to the open file `file'.  The image is written
  1041. in the Portable Bitmap format P4 (pbm), the same format SIPP is using
  1042. when rendering a line drawing to a file.
  1043.  
  1044. 
  1045. File: sipp,  Node: Shaders,  Next: Object primitives,  Prev: Rendering,  Up: Top
  1046.  
  1047. Shaders
  1048. *******
  1049.  
  1050.    A major feature in SIPP is the very flexible way shading functions
  1051. are handled. Each surface has a pointer to a function that is called
  1052. whenever a point on that surface is rendered. The interface to these
  1053. shading functions is well defined so it is quite easy for a user to
  1054. write his own. SIPP also provides a number of shaders in the library for
  1055. various effects.
  1056.  
  1057. * Menu:
  1058.  
  1059. * Provided shaders::            Shaders provided with the library
  1060. * Writing your own shaders::    How to write your own shading functions
  1061.  
  1062. 
  1063. File: sipp,  Node: Provided shaders,  Next: Writing your own shaders,  Up: Shaders
  1064.  
  1065. Provided shaders
  1066. ================
  1067.  
  1068.    This section describes all the shaders that are provided with SIPP.
  1069. To use any of them, except `basic_shader()', the program must contain
  1070. the following line:
  1071.      #include <shaders.h>
  1072.    The most important thing to know when using a shader is how it
  1073. represents its surface description and what this description should
  1074. contain. All provided shaders in SIPP use a normal C struct as surface
  1075. description.
  1076.  
  1077. * Menu:
  1078.  
  1079. * The basic shader::    The basic shader used by most of the rest of
  1080.                         the shaders
  1081.  
  1082. * The Phong shader::    The standard Phong shading model.
  1083. * The Strauss shader::  More realistic shader by Paul Strauss.
  1084. * The marble shader::   A shader creating a marble pattern
  1085. * The granite shader::  A shader creating a granite like pattern
  1086. * The wood shader::     A shader creating a wooden pattern
  1087. * The bozo shader::     A somewhat whimsical shader creating a pattern
  1088.                         originally used by Bozo the clown.
  1089.  
  1090. * The mask shader::     A shader usable when the contents of a mask
  1091.                         should control which one of two shaders will
  1092.                         determine the color of each pixel.
  1093. * The bumpy shader::    A shader which creates the illusion of a bumpy
  1094.                         surface
  1095. * The planet shader::   Creates a 3-dimensional pattern of a planet surface
  1096.  
  1097. 
  1098. File: sipp,  Node: The basic shader,  Next: The Phong shader,  Up: Provided shaders
  1099.  
  1100. The basic shader
  1101. ----------------
  1102.  
  1103.    The basic shader in SIPP, `basic_shader()', is basically a Phong
  1104. shader but, with some influence from Blinn, the "shinyness" of the
  1105. surface is described with a number in the range [0, 1] and the
  1106. implemented "shinyness" function changes with this constant in a more
  1107. natural way (at least in our opinion).
  1108.  
  1109.    Surface description:
  1110.      typedef struct {
  1111.              double ambient;
  1112.              double specular;
  1113.              double c3;
  1114.              Color  color;
  1115.              Color  opacity;
  1116.      } Surf_desc;
  1117.  
  1118.    * `ambient' is a number in the range [0, 1] specifying how much of
  1119.      the surface color that is visible when the object is not lit by any
  1120.      lightsource.
  1121.  
  1122.    * `specular' is a number in the range [0, 1] specifying how much
  1123.      light that is reflected in a specular highlight on the surface.
  1124.  
  1125.    * `c3' is also a number in the range [0, 1]. It specifies how
  1126.      "shiny" the surface is. 0 means a very shiny surface while 1
  1127.      indicates a rather dull one.
  1128.  
  1129.    * `color' is simply the color of the surface.
  1130.  
  1131.    * `opacity' specifies how opaque the surface is. This is stored as a
  1132.      color to allow different opacities for the different color bands.
  1133.      The values should be in the range [0, 1] with 1 indicating a
  1134.      completely opaque object and 0 a completely transparent
  1135.      (invisible) one.
  1136.  
  1137. 
  1138. File: sipp,  Node: The Phong shader,  Next: The Strauss shader,  Prev: The basic shader,  Up: Provided shaders
  1139.  
  1140. The Phong shader
  1141. ----------------
  1142.  
  1143.    `phong_shader()' implements the well known Phong illumination model.
  1144.  
  1145.    Surface description:
  1146.      typedef struct {
  1147.              double ambient;
  1148.              double diffuse;
  1149.              double specular;
  1150.              int    spec_exp;
  1151.              Color  color;
  1152.              Color  opacity;
  1153.      } Phong_desc;
  1154.  
  1155.    * `ambient' is a number in the range [0, 1] specifying how much of
  1156.      the surface color that is visible when the object is not lit by any
  1157.      lightsource.
  1158.  
  1159.    * `diffuse' is a number in the range [0, 1] specifying how much
  1160.      light that is reflected diffusely from the surface.
  1161.  
  1162.    * `specular' is a number in the range [0, 1] specifying how much
  1163.      light that is reflected in a specular highlight on the surface.
  1164.  
  1165.    * `spec_exp' is the exponent in the specular highlight calculation.
  1166.      It specifies how "shiny" the surface is. Useful values are about 1
  1167.      to 200, where 1 is a rather dull surface and 200 is a very shiny
  1168.      one.
  1169.  
  1170.    * `color' is the color of the surface.
  1171.  
  1172.    * `opacity' specifies how opaque the surface is. This is stored as a
  1173.      color to allow different opacities for the different color bands.
  1174.      The values should be in the range [0, 1] with 1 indicating a
  1175.      completely opaque object and 0 a completely transparent
  1176.      (invisible) one.
  1177.  
  1178. 
  1179. File: sipp,  Node: The Strauss shader,  Next: The marble shader,  Prev: The Phong shader,  Up: Provided shaders
  1180.  
  1181. The Strauss shader
  1182. ------------------
  1183.  
  1184.    `strauss_shader()' is a shader designed by Paul Strauss at Silicon
  1185. Graphics Inc. and published in IEEE CG&A Nov. 1990. In his article he
  1186. explains that most shading models in use today, e.g. Phong,
  1187. Cook-Torrance, are difficult to use for non-experts, and this for
  1188. several reasons.  The parameters and their effect on a surface are non-
  1189. intuitive and/or complicated. The shading model Strauss designed has
  1190. parameters that is easy to grasp and have a reasonably deterministic
  1191. effect on a surface, but yet produces very realistic results.
  1192.  
  1193.    Surface description:
  1194.      typedef struct {
  1195.              double  ambient;
  1196.              double  smoothness;
  1197.              double  metalness;
  1198.              Color   color;
  1199.              Color   opacity;
  1200.      } Strauss_desc;
  1201.  
  1202.    * `ambient' is a number in the range [0, 1] specifying how much of
  1203.      the surface color that is visible when the object is not lit by any
  1204.      lightsource.
  1205.  
  1206.    * `smoothness' is a number in the range [0, 1] that describes how
  1207.      smooth the surface is. This parameter controls both diffuse and
  1208.      specular reflections. 0 means a dull surface while 1 means a very
  1209.      smooth and shiny one.
  1210.  
  1211.    * `metalness' is a number in the range [0, 1]. It describes how
  1212.      metallic the material is. It controls among other things how much
  1213.      of the surface color should be mixed into the specular reflections
  1214.      at different angles. 0 means a non-metal while 1 means a very
  1215.      metallic surface.
  1216.  
  1217.    * `color' is the color of the surface.
  1218.  
  1219.    * `opacity' specifies how opaque the surface is. This is stored as a
  1220.      color to allow different opacities for the different color bands.
  1221.      The values should be in the range [0, 1] with 1 indicating a
  1222.      completely opaque object and 0 a completely transparent
  1223.      (invisible) one.
  1224.  
  1225. 
  1226. File: sipp,  Node: The marble shader,  Next: The granite shader,  Prev: The Strauss shader,  Up: Provided shaders
  1227.  
  1228. The marble shader
  1229. -----------------
  1230.  
  1231.    `marble_shader()' uses a three dimensional texture to create the
  1232. appearance of marble. The texture is created by mixing distorted strips
  1233. of one color into another "base" color of the surface.
  1234.  
  1235.    Surface description:
  1236.      typedef struct {
  1237.              double ambient;
  1238.              double specular;
  1239.              double c3;
  1240.              double scale;
  1241.              Color  base;
  1242.              Color  strip;
  1243.              Color  opacity;
  1244.      } Marble_desc;
  1245.  
  1246.    * `ambient, specular, c3' and `opacity' have the same meaning as in
  1247.      `basic_shader()' (see *Note The basic shader::).
  1248.  
  1249.    * `scale' describes how much the texture coordinates should be scaled
  1250.      before applying the texture. When scaling get larger, the object
  1251.      will get larger in comparison to the marble pattern.
  1252.  
  1253.    * `base' is the base color of the surface.
  1254.  
  1255.    * `strip' is the color of the strips which is mixed in with the base
  1256.      color.
  1257.  
  1258. 
  1259. File: sipp,  Node: The granite shader,  Next: The wood shader,  Prev: The marble shader,  Up: Provided shaders
  1260.  
  1261. The granite shader
  1262. ------------------
  1263.  
  1264.    `granite_shader()' is very similar to `marble_shader()'. It also
  1265. mixes two colors to create a three dimensional texture, but the mixing
  1266. is done in a different manner so the result should look like granite.
  1267.  
  1268.    Surface description:
  1269.      typedef struct {
  1270.              double ambient;
  1271.              double specular;
  1272.              double c3;
  1273.              double scale;
  1274.              Color  col1;
  1275.              Color  col2;
  1276.              Color  opacity;
  1277.      } Granite_desc;
  1278.  
  1279.    * `ambient, specular, c3' and `opacity' have the same meaning as in
  1280.      `basic_shader()' (see *Note The basic shader::).
  1281.  
  1282.    * `scale' describes how much the texture coordinates should be scaled
  1283.      before applying the texture. When scaling get larger, the object
  1284.      will get larger in comparison to the granite pattern.
  1285.  
  1286.    * `col1' and `col2' are the two colors that are mixed.
  1287.  
  1288. 
  1289. File: sipp,  Node: The wood shader,  Next: The bozo shader,  Prev: The granite shader,  Up: Provided shaders
  1290.  
  1291. The wood shader
  1292. ---------------
  1293.  
  1294.    `wood_shader()' creates a simulated wood texture on a surface.  It
  1295. uses two colors, one as the base (often lighter) color of the wood and
  1296. one as the color of the (often darker) rings in it.  The rings are put
  1297. into the base color about the x-axis and are then distorted slightly. A
  1298. similar pattern is repeated at regular intervals to create an illusion
  1299. of logs or boards.
  1300.  
  1301.    Surface description:
  1302.      typedef struct {
  1303.              double ambient;
  1304.              double specular;
  1305.              double c3;
  1306.              double scale;
  1307.              Color  base;
  1308.              Color  ring;
  1309.              Color  opacity;
  1310.      } Wood_desc;
  1311.  
  1312.    * `ambient, specular, c3' and `opacity' have the same meaning as in
  1313.      `basic_shader()' (see *Note The basic shader::).
  1314.  
  1315.    * `scale' describes how much the texture coordinates should be scaled
  1316.      before applying the texture. When scaling get larger, the object
  1317.      will get larger in comparison with the wood texture.
  1318.  
  1319.    * `base' and `ring' are the colors in the wood.
  1320.  
  1321. 
  1322. File: sipp,  Node: The bozo shader,  Next: The mask shader,  Prev: The wood shader,  Up: Provided shaders
  1323.  
  1324. The bozo shader
  1325. ---------------
  1326.  
  1327.    `bozo_shader()' uses a random number, correlated with the three
  1328. dimensional texture coordinates, to chose a color from a fixed set. The
  1329. user supplies an array of colors to choose from.
  1330.  
  1331.    Surface description:
  1332.      typedef struct {
  1333.              Color  colors[];
  1334.              int    no_of_cols;
  1335.              double ambient;
  1336.              double specular;
  1337.              double c3;
  1338.              double scale;
  1339.              Color  opacity;
  1340.      } Bozo_desc;
  1341.  
  1342.    * `colors' are an array of colors with `no_of_cols' entries.
  1343.  
  1344.    * `ambient, specular, c3' and `opacity' have the same meaning as in
  1345.      `basic_shader()' (see *Note The basic shader::).
  1346.  
  1347.    * `scale' describes how much the texture coordinates should be scaled
  1348.      before applying the texture.
  1349.  
  1350. 
  1351. File: sipp,  Node: The mask shader,  Next: The bumpy shader,  Prev: The bozo shader,  Up: Provided shaders
  1352.  
  1353. The mask shader
  1354. ---------------
  1355.  
  1356.    `mask_shader()' uses a user provided decision function to mask
  1357. between two different shaders. The decision function is passed all three
  1358. texture coordinates and returns TRUE or FALSE.
  1359.  
  1360.    The decision function should have the following interface:
  1361.      bool
  1362.      my_masker(mask, u, v, w)
  1363.              my_mask_data *mask;
  1364.              int           u, v, w;
  1365.  
  1366.    * `my_mask_data' is a pointer to any data structure that the decision
  1367.      function needs. A common use for `mask_shader()' is to use a bitmap
  1368.      to mask something onto a surface, in this case `my_mask_data' could
  1369.      point to the bitmap itself.
  1370.  
  1371.    * `u, v' and `w' is the interpolated texture coordinates sent to the
  1372.      shader.
  1373.  
  1374.    Surface description:
  1375.      typedef struct {
  1376.              Shader *t_shader;
  1377.              void   *t_surface;
  1378.              Shader *f_shader;
  1379.              void   *f_surface;
  1380.              void   *mask_data;
  1381.              bool  (*masker)();
  1382.      } Mask_desc;
  1383.  
  1384.    * The shader `t_shader' and the surface description `t_surface' is
  1385.      used to shade the surface whenever the decision function returns
  1386.      TRUE.
  1387.  
  1388.    * The shader `f_shader' and the surface description `f_surface' is
  1389.      used to shade the surface whenever the decision function returns
  1390.      FALSE.
  1391.  
  1392.    * `mask_data' points to any data structure the decision function
  1393.      need.
  1394.  
  1395.    * `masker' is a pointer to the decision function.
  1396.  
  1397.